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ABBREVIATIONS AND ACRONYMS 





ABBREVIATIONS AND ACRONYMS | 





Abbreviation Meaning 

WSDL Web Services Description Language 
XML Extensible Markup Language 

XSD XML Schema 

ECAS European Citizen Action Service 


Table 1: Abbreviations and Acronyms 


DEFINITIONS | 


Term Meaning 





CELLAR The CELLAR can be seen as the content repository module. This 
application aims to store all content and metadata needed by the 
Publications Office and its applications. 


Table 2: Definitions 
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1 INTRODUCTION 


1.1 PURPOSE OF THE DOCUMENT 


The aim of this User Manual is to describe how to use the web service provided by the EUR-Lex 2012 
system. This document may be used by all users interested in the usage of this web service. 


1.2 SCOPE OF THE DOCUMENT 


This User Manual refers to the EUR-Lex web services. 


1.3 INTENDED AUDIENCE 


The present document is intended to be read by the following people: 


e EUR-Lex 2012 public users; 


1.4 STRUCTURE OF THE DOCUMENT 


The document is organised as follows: 
e Chapter 1 - Introduction provides an overview of the purpose of this document, and the 
intended audience; 


e Chapter 2 - Registration explains how the different functionalities related to web services 
that are accessible from the new EUR-Lex 2012 interface; 


e Chapter 3 - Use the web service explains how to use the EUR-Lex 2012 web services with a 
free testing tool like SOAPUI; 


e Chapter 4 - Expert search syntax explains the syntax of the expert search; 
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2 REGISTRATION 


The new EUR-Lex 2012 provides a web service opened to external user in order to search for legal 
content. It is a convenient way to perform search queries on the legal content of EUR-Lex without 
having to use the different search forms present on the website. The search results provided are 
contained in a structured XML compliant a specific schema definition. 


In order to use the web service, the user must be registered in the new EUR-Lex and must subscribe 
to the web service. 


2.1 WEB SERVICE REGISTRATION 


The user can access the web services page using the link present in the right menu as shown on the 
next picture. 


My EUR-Lex 


â Signin 
or Register» 


My searches (0) 
My items (0) 
My RSS feeds (0) 


A RSS feeds 


oO 
o Webservice registration 


© Guided Tour 
lll Statistics 


F1 We'd like to hear from you 


Twitter W y 


Figure 1: Link to the web service 


The user has to register in order to have access to the service. An administrator will check the 
registration data and allow or forbid the use of the web services. 
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The link to the registration form is available on the web service page when the user is not yet 
registered to the web service. 





Webservice registration O2 € 
EUR-Lex offers a Web Service to allow registered external parties to query and retrieve data from the EUR-Lex database. 
JA Web Service is a software system designed to support interoperable machine-to-machine interaction over a network. 


The EUR-Lex Web Service provides the data in XML and offers query options similar to Expert (Advanced) search. If you require a 


simpler way to stay up to date with EUR-Lex data, LexAlert offers notifications by RSS 








Figure 2: Link to register for the web services 


Clicking on the Register button redirects the user to the registration form. 












































Use 
Used data * 
Final use of data * 
Calling application * a 
Days of use * 
MON TUE WED THI FRI SAT SUN 
m A A 
Call frequency * 
Comments * 
User Organisation 
Username * |use Last Name * 
Last Name * Lastnamet Address * 
First name* Firstnamet ZIP code * 
Email * user1@eurlex.eu Country * 
Phone number Phone number 
Disclaimer 
Text3 to be defined by Publication office 
|| 1 accept to respect conditions of use of the web services describes on this page 
Text4 to be defined by Pubtication office 

















Figure 3: Web services registration form 


The form contains the following fields: 


EDITABLE FIELDS 


Field Description Mandatory 
Description of the data that will be used in the scope of the 
vacu data utilisation of the web service. Nes 
Final use of data The description of the data usage Yes 
Calling 7 f ee Yes 
application Description of the calling application 
Days of use Selection of the day of the week when the service will be used. | Yes 
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Call frequency 
Comments 
Username 
First name 
Last name 
Phone number 
Email address 
Name 
Address 

ZIP code 
Country 
Phone number 


| accept the 
terms of usage 


One check box by week day. 
The number of calls per day that is foreseen 
Some additional comments 


The username of the user is prefilled and in a read-only mode. 


The first name of the applicant 

The last name of the applicant 

The phone number of the applicant 
The email address of the applicant 
The name of the organisation 

The address of the organisation 

The ZIP code of the organisation 

The country of the organisation 

The phone number of the organisation 
Indicates that the user accepts the terms of usage of the web 
service 


Table 3: Editable fields for the web services demand 


Yes 
Yes 
N/A 
Yes 
Yes 
No 

Yes 
Yes 
Yes 
Yes 
Yes 
No 

Yes 


Version: 1.01 


The demand is sent to the administrator after clicking on Save. The administrator checks regularly all 


the requests and accept or reject each of them. The user is informed by email about the details of 


the web service access. 
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3 USE THE WEB SERVICE 


This section describes how to use the web service; an example is provided below using SoapUI, an 
open source testing tool. 


The query done with the web service must respect a particular syntax. The request that have to be 
provided is detailed in the next section. 


Finally, it will describe the complete procedure, step by step, to perform a web service request using 
SoapUI on the EUR-Lex FrontOffice and also a simple and usual way. 


3.1 ACCESS THE WEB SERVICES SPACE 

3.1.1 VIEW THE WSDL 

When the status of the user is granted, he is allowed to use the web service. 

About EUR-Lex | Site 


EUR-Lex 


Access to European Union law 


EUROPA >? EU law and publications ? EUR-Lex ? Webservice registration 





Home Official Journal EU law and related documents National law Legislative procedures More 


Webservice registration 


Your access to the webservice is active. 


You can use the webservice by using, for instance SoapUi. 


* View the WSDL 


* To increase your calls limit please follow the procedure. 
* Unsubscribe from the webservice 


* Reset password and send it by email 


Figure 4: Link to the WSDL of the web service 


The user is able to download the WSDL of the web service to retrieve the information necessary to 
use it. 


3.1.2 CHANGE THE LIMITS OF THE WEB SERVICE DEMAND 


The number of calls that can be performed each day is limited. In order to change the limitations, the 
user can send a demand to increase or decrease the limitations for the web services demands. To 
achieve this, he needs to use the link shown on the next figure in order to see the procedure to 


apply: 
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EUR-Lex About EUR-Lex | Site 


Access to European Union law 


EUROPA ? EU law and publications ? EUR-Lex ) Webservice registration 


Home Official Journal EU law and related documents National law Legislative procedures More 


Webservice registration 


Your access to the webservice is active. 


You can use the webservice by using, for instance SoapUi. 


* View the WSDL 


* To increase your calls limit please follow the procedure. 








* Unsubscribe from the webservice 


* Reset password and send it by email 


Figure 5: Link to the change the limitations of a web service demands 


3.1.3 UNSUBSCRIBE FROM THE WEB SERVICE 


If the user does not need to use the web services anymore, he can unsubscribe from the web 
services using the link shown on the next figure: 


FUR-Lex About EUR-Lex | Site 


Access to European Union law 


EUROPA °? EU law and publications ? EUR-Lex ? Webservice registration 


Home Official Journal EU law and related documents National law Legislative procedures More 


Webservice registration 


Your access to the webservice is active. 





You can use the webservice by using, for instance SoapUi. 


* View the WSDL 


* To increase your calls limit please follow the procedure. 


* Unsubscribe from the webservice 


* Reset password and send it by email 


Figure 6: Link to unsubscribe from the web service 


A form is displayed asking the user to give the reason of withdrawal. 
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Enter the reason of your 
unsubscribe 





Figure 7: Field to enter the reason of withdrawal from the web services 


The withdrawal reason is saved after clicking on unsubscribe and the access to the web service is 
closed. 


3.1.4 RESET PASSWORD AND SEND IT BY EMAIL 


If the user doesn’t remember his password for the web service, he can ask to generate a new one by 
clicking on the following link: 





J EUR-Lex About EUR-Lex | Site 


Access to European Union law 


EUROPA ? EU law and publications ? EUR-Lex ? Webservice registration 





Home Official Journal EU law and related documents National law 


Webservice registration 


Your access to the webservice is active. 


Legislative procedures More 


You can use the webservice by using, for instance SoapUi. 


* View the WSDL 


* To increase your calls limit please follow the procedure. 


* Unsubscribe from the webservice 


* Reset password and send it by email 


Figure 8: Link to reset the password for the web service 


Once the link clicked, an email is sent to the user with the newly generated password. 
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3.2 XML INPUT 


The input of the web service must respect the soap envelop structure. The soap envelop is composed 
of a Header and Body elements. The content of Body must respect an XSD defined by EUR-Lex. 
Moreover, the Header must contain information about security. The template to be used by the web 
service is the following: 


<soap:Envelope xmlins:sear="http://eur-lex.europa.eu/search" 
| xmlns :soap="http://www.w3.0rg/2003/05/soap-envelope"> 
| <soap:Header> 
i <wsse:Security soap:mustUnderstand="true" xmlns:wsse="http://docs.oasis- 
open. org/wss/2004/01/oaSis -200401-wss-wssecurity-secext-1.0.xsd"> 
<wsse:UsernameToken wsu:Id="UsernameToken-3" xmlns:wsu="http://docs.oasis- 
open. org/wss/2004/01/oasis -200401-wss-wssecurity-utility-1.0.xsd"> 
i <wsse:Username>${EUR-Lex username}</wsse:Username> 
i <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis - 200401 - 
wss-username-token-profile-1.0#PasswordText">${WS password}</wsse:Password> 
| </wsse:UsernameToken> 
</wsse:Security> 
</soap:Header> 
<soap : Body> 
<sear : searchRequest> 
<sear:expertQuery>${expert query}</sear:expertQuery> 
<sear :page>${page}</sear : page> 
<sear :pageSize>${pageSize}</sear : pageSize> 
<sear:searchLanguage>${search language}</sear : searchLanguage> 
</sear : searchRequest> 
i </ soap : Body> 
</soap:Envelope> 


You can find below the description of each required field: 


e wsse:Username: Username used by the user to log in EUR-Lex. This is provided by ECAS. 


e wsse:Password: The password received by email once the user registration to the web 
services has been accepted by an administrator. 


e  sear:expertQuery: The query used by the search engine to retrieve documents. The following 
chapter explains the syntax of the expert search. 


e searc:page: The page of the search results, as the system uses the pagination. For instance, 
the user is allowed to retrieve the 10 results of the second page. It corresponds to the 
documents from 10 to 20. 


e sear:pageSize: The size of the page used in the pagination. 


e sear:searchLanguage: The search language. When using a web service client, a list of value is 
provided for the search language. 


All these fields are required to perform a query. It is really important to respect the defined 
namespaces. 
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An error will be thrown if: 


e One of the field value is missing; 

e The user accessing web service is not granted by an administrator; 

e The syntax of the expert query is invalid (see chapter Expert search syntax); 

e The page size is greater than the defined limit size. By default, the maximum value is 100; 


e The number of web service call during the current day is greater than the defined limit. The 
default value is 1000. 


3.3 USE THE WEB SERVICE WITH SOAPUI 


With an easy-to-use graphical interface, SoapUI allows you to easily and rapidly create and execute 
automated functional, regression, compliance, and load tests. It also allows the user to quickly test 
soap web service. The version of SOAPUI used for the elaboration of this document was 4.0.1. 


You can freely download this software on the following website: 
http://sourceforge.net/projects/soapui/files/ 


The next sections explain how to use SOAPUI to perform web service against the new EUR-Lex. 


3.3.1 CREATE A NEW SOAPUI PROJECT 


You can retrieve the URL of the WSDL via the Front Office interface, as described in the section 3.1.1. 


Start SoapUI and create a new project: File -> New soapUI Project and enter the following parameter, 
as described on the Figure 9: New soapUi project: 
e Project Name: whatever you want 


e Initial WSDL/WADL: The URL retrieved via the Front Office interface (for instance http://eur- 
lex.europa.eu/eurlex-ws? wsdl) 


e Create Requests: checked 
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© New soapUl Project ts 


New soapUI Project 
Creates a new soapUI Project in this workspace 


Project Name 
Initial WSDL/WADL: _ | http://eur-lex.europa.eu/eurlex-ws?wsdl Browse... 


Create Requests: [V] Create sample requests for all operations? 








Create TestSuite: [C] Creates a TestSuite for the imported WSDL or WADL 

Create MockService: [_] Creates a Web Service Simulation of the imported WSDL 

Add REST Service: 

Relative Paths: C] Stores all file paths in project relatively to project file (requires save) 

Create Web TestCase: |] Creates a TestCase with a Web Recording session for functional web testing 








Figure 9: New soapUi project 
3.3.2 CREATE A QUERY WITH SOAPUI 
This will automatically create a sample request to be fulfilled. Then, navigate to the form view of the 
sample request and fill the form: 
e expertQuery: the query you want to perform, in the expert syntax; 
e page: the page you want to retrieve; 
e pageSize: the number of results you want to retrieve in a page; 


e searchLanguage: the search language. 
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Figure 10: Web service form 


These elements are described in the section XML Input. 


Then, you need to add the authentication to the request. Click on the XML view of the request, and 
click on the Aut button (bottom left hand corner) and enter the following information in the form: 


e Username: the username of the username registered to the Front Office web services 


e Password: the password received when you registered to the Front Office web services 


ELX-WS-Web Service User Manual-v1.01.doc Page 17 of 34 





Development and Maintenance 
of the new EUR-Lex 
Office des publications de l'Union européenne 











Ref: ELX-WS-Web Service User Manual | Version: 1.01 











b = ÿ EG D a @ lhttp://eur-lex.europa.eu/EURLexWebService 


soap:Envelope xmlns:soap="http: //www.w3.org/Z003/05/soap-envelope" xm 
*<soap:Header/> 
<soap:Body> 
“sear: searchRequest> 
<sear:expertQuery>?</sear:expertQuery> 
*sear: page>?</sear:page> 
sear: pageSize>?</sear:pageSize> 
*<sear: searchLanquage>?</sear: searchLanquage> 
</sear:searchRequest> 


Form | Outline | Ra 


</soap:Body> 








Figure 11: Authentication 


Finally, right click in the XML view and click “Add WSS Username Token”. Ensure that “PasswordText” 
is selected and click OK. The result is shown on the following figure. A username token has been 
added in the request headers. 





“soap: Envelope xmlns:sear="http: //eur-lex.europa.eu/search" xmlns:soap="http: //wint.w3.org/2003/05/soap-envelope"> [al 
<soap:Header> 









J.X 


<wsse:UsernameToken w: “http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> 


UsernameToken-5" xmlns:wsu= 


<sse:Usernanpp>usernane<Jusse:Usernane> 
<wsse: Password Type="http://docs.oasis-open.orgy/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText wsse: Passw 
<wsse:Nonce EncodingType="http: //docs. oasis-open. org/wss/2004/0l/oasis-20040l-wss-soap-message-security-l.0#Base64Binary">x5VwJZoYZylk0x9 


swsu: Created>2012-03-09T14:21:14.6362</wsu: Created> 
</wsse:UsernameToken> 
</wsse:Security> 
</soap:Header> 





v 
Is 
z 
(a) 

E 
£ 





<soap:Body> 
“sear: searchRequest> 
“sear: expert Query>?</sear: expertQuery> 
<sear:page>?</sear:page> 
“sear: pageSize>?</sear:pageSize> 
“sear: searchLanquage>?</sear: searchLanguage» 
«/sear: searchRequest> 
</soap:Body> 








</soap: Envelope 


Figure 12: Username Token element 
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As you can see in the previous figure, the username and the password entered in the Aut field have 
been automatically added in the Header. 


To perform the same query many times, you need to delete the lines with the xml elements 


<wsse:Nonce> and <wsu: Created>. 


> 


To start the request, click on to retrieve the results. 


If you have some difficulties to fill the web service request, you can retrieve the template to use to 
perform a web service query thanks to the FrontOffice web service template, as described in the 
section XML result. 


The following figure shows you the result of a web service request: 











(a |<soap: Envelope xmins:sear="http: //eur-lex.europa.eu/search" xmlns:=soap="http: /|4]|€\(S [<s: Envelope mulns:S="http: //mmr.w3.org/Z003/05/soap-envelope"> a 
E <soap:Header> £ <S:Body> | 
z <usse: Security soap:mustUnderstand="true" xmlns:wsse="http: //docs. oasis- z| <eurlex:searchResults xsi:schenaLocation="http://eur-lex.europa.eu/search http: 
€ <wsse:UsernameToken wsu:Id="UsernameToken-3" xmlns:wsu="http: //docs. o| g| <numhits>7</numhits> 
= <usse:Username>userl</usse:Username> zl <totalhits>7</totalhits> 
= <wsse: Password Type="http://docs.oasis-open.org/wss/2004/01/oasis- = | <page>1</page> 
= </wsse:UsernameToken> é | <language-en</language> 
= </wsse:Security> —| <result> 
E </soap:Header> ë| <reference>eng_cellar:al09243e-487c-475d-8fld-661d67a5£695_en</reference> 
2 <soap:Body> z <rank>1</rank> 
<sear:searchRequest> 8| <content> 
<expertQuery>DN=3*</expertQuery> | <NOTICE> 
<page>1</page> <WORK> 
<pageSize>10</pageSize> <URI> 
<searchLanguage>en</searchLanguage> <VALUE>http: //cellar-dev. publications. europa. eu/resource/cella 
</sear: searchRequest> <TYPE>cellar</TYPE> 
</soap:Body> <IDENTIFIER>al09243e-487c-475a-8 f1d-661d67a5 £695</IDENTIFIER> 
</soap: Envelope </URI> 
<SAMEAS> 
<URI> 
<VALUE>http: //cellar-dev. publications. europa. eu/resource/ce 
<TYPE>celex</TYPE> 
<IDENTIFIER>32008D0438</IDENTIFIER> 
</URI> 
</SAMEAS> 
<SAMEAS> 
<URI> 
<VALUE>http: //cellar-dev. publications. europa. eu/resource/o 
<TYPE>03</TYPE> 
<IDENTIFIER>JOL_Z008_155_R_0015_01</IDENTIFIER> 
</URI> 
</SAMEAS> 
<WORK_CREATED_BY_AGENT> 
<URI> 


<VALUE>http: //publications. europa. eu/authority/fd_010/+20C 
<TYPE> fd_010</TYPE> 
= <IDENTIFIER»#20CCIC</IDENTIFIER> 


bia)! CRE Lb 
(Aut | Headers (0)| Attachments (0)| WS-A] WS-RM | JMS Headers | JMS Property (0)| XSD (searchLangud < + | | Headers (6) [Attachments (0) | SSL Info| WSS (0) | JMS (0) | XSD (2)| Table (1) XML| Doc | Coverage] 
























































Figure 13: Results 


3.4 XML RESULT 


The result of the web service is a Soap Envelope. That envelop contains a Body element which 
contains XML elements that respect an XSD that can be retrieved from EUR-Lex. 


The root element in the Body is the searchResults element. It contains: 


e numhits: the number of results in the page; 
e totalhits: the total number of results related to the query; 


e page: the current page of results; 
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e language: the search language; 

e result: the element related to a result. This element contains: 
O reference: the CELLAR reference; 
o rank: the index of the document; 


o document_link: links to the manifestations of the document (at word, tiff, html or pdf 
format), if any manifestation of the document exist; 


o content: the metadata of the document; 


You can find below a sample of the result. 


<S:Envelope xmins:S="http://www.w3.org/2003/05/soap-envelope"> 
| <S:Body> 
i <searchResults xsi:schemaLocation="http://eur-lex.europa.eu/search 
http://localhost:7001/eurlex-frontoffice/eurlex-ws?xsd=3" xmlns="http://eur - 
! lex.europa.eu/search" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 
<numhits>10</numhits> 
<totalhits>1946</totalhits> 
<page>1</page> 
<language>en</language> 
<result> 
<reference>eng_cellar :93836665-712f -4444-a1e6-dadad5607e80_en</reference> 
<rank>1</rank> 
<content> 
<NOTICE> 
<EXPRESSION> 
<EXPRESSION_TITLE> 
<VALUE>Decision on the ...</VALUE> 
</EXPRESSION_TITLE> 
<EXPRESSION_USES_LANGUAGE> 
<URI> 
<IDENTIFIER>ENG</IDENTIFIER> 
</URI> 
</EXPRESSION_USES_LANGUAGE> 


The content element will contain some metadata of the document. The list of provided metadata 


depends on query: 
e |f the expert query contains a SELECT clause, the provided metadata will only be those 
present in the SELECT clause; 


e If the expert query doesn’t contain any SELECT clause, the list metadata provided will be the 
list defined in the default search profile of the user, in the EUR-Lex 2012 website. 


To know the possibilities of the expert syntax, please refer to the section Expert search syntax. 
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3.5 GET WEB SERVICE TEMPLATE 


Getting the web service template is a very useful way to retrieve the web service request to be used 
to perform the same request that the one performed on the EUR-Lex website. It allows you to 
perform web service requests even if you don’t know the expert query syntax. 


Each user who has a web service status granted can get the web service template for every query he 
performs. 


To get the web service template after a search, the user needs to click on the following icon: 





EUROPA ? EU law and publications ? EUR-Lex ? Expert search ? Search results 

Home Official Journal EU law and related documents National law Legislative procedures More 

Refine query 2118) share 
Search criteria ~ 


v* By domain 
EU law and related Query: TI ~ transport OR TE ~ transport, Search language: English 


documents (42616) 








4) Edit in expert search 2) Save to My searches IA] Create in My RSS feeds 
National law (194) : 
WebService template F1 Save to My items 
Legislative procedures 
(160) 
v By subdomain Sort by Default v Descending + 


(28336 
All (38336) M] Results 1 - 10 of 55294 Export selection/Export all | Change displayed metadata | Clear selection 





Preparatory acts (15512) 


Legislation (12014) 
fj 01960R0011-19860701- Regulation No 11 concerning the abolition of discrimination in transport rates and 


Consolidated legislat 
et ee ee conditions, in implementation of Article 79 (3) of the Treaty establishing the European Economic Community 





(4680) 
Parliamentary questions Form: Regulation Author: Council of the European Union 
(4280) Direct text access J Date of document: 27/06/1960 

See more... = 


= 01960R0011-20080710: Reaulation No 11 concernina the abolition of discrimination in transport rates and 


Figure 14: Link to get the web service template 


After clicking on the icon, a new window is displayed giving the request template. The user just needs 
to copy the provided XML and paste it in the XML view of the SOAPUI project created. Before 
launching the search in the WSDL, the user only needs to insert his password in the query. 
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WebService template 


Here is a web service template of your previous query. Just replace the password by the one you received after your web service 
registration. 


<soap:Envelope xmlns:soap="http:/ /www.w3.0rg/2003/05/soap-envelope" xmlns:sear="http://eur-lex.europa.eu/search"> 
<soap:Header> 
<wsse:Security xmlns:wsse="http:/ /docs.oasis-open.org/wss/'2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" 
soap:mustUnderstand="true"> 
<wsse: UsernameToken xmlns:wsu="http:/ /docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" 
wsu:Id="UsernameToken-1"> 
<wsse:Username>heneffem< /wsse:Username> 
e ~ is-open.org/wss/2004/01/oasis-200401-wss-username-token-profile- 
/wsse:Password> 


</wsse:Security> 


</soap:Header> 
<soap:Body> 
<sear:searchRequest> 
<sear:expertQuery>QUICK_SEARCH = "transport"</sear:expertQuery> 
<sear:page>1</sear:page> 
<sear:pageSize>10</sear:pageSize> 
<sear:searchLanguage>en</sear:searchLanguage> 
</sear:searchRequest> 
</soap:Body> 
</soap:Envelope> 





Figure 15: Web service template 
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4 EXPERT SEARCH SYNTAX 


The Expert search functionality is used to have a flexible search option that allows the combination 
of many criteria. Each expert search query must comply with a specific syntax described in this 
chapter. 


The basic rule is to use the following scheme: metadata operator value. The criteria to enter are 
written as pairs of metadata and corresponding value. 


The user can easily check if the syntax of the query is correct by using the expert search in the EUR- 
Lex website. Some data helpers are provided as well to help the user with the use of the different 
metadata. 


EUROPA >? EU law and publications ? EUR-Lex ) Expert search 


Home § Official Journal EU lawandrelated documents Nationallaw Legislative procedures More 


Expert search ?| (i) share 


| o The query is valid. | 








Search language English (en) X 
Expert query DN=3200?D* 7 | oR | | ase | E 
EE 


Search fields Please select a field 


Collapse all / Expand all 
Documents 


> Text data 

> Descriptors 

> Bibliographic details 
> Dates 


m 


> Relationship between documents 
> Case law/The text data 





> Case law/Parties 


Figure 16: Expert search 


4.1 WHERE CLAUSE 


4.1.1 GENERAL FEATURES 


e Truncation, as for example a wildcard (*) or single character (?) can be used in the search 
terms. The wildcard stands for 0 to n characters and ‘?’ replaces one single character; 


Example: DN=3200?D* will search for all decision documents of sector 3 within the 
years 2000 to 2009. 


e Boolean operators can be used to separate and group search criteria or values in different 
ways. The expert search includes three different operators: ‘AND’, ‘OR’ and ‘NOT’. AND is 
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used to impose that all criteria must be fulfilled, ‘OR’ is used when at least one criteria is 
mandatory and ‘NOT’ will exclude some criteria. 

Examples: DN = 32000* AND TI ~ Transport 
DN = 32000* OR TI ~“ Transport 
DN = 32000* NOT TI ~ Transport 
DN = 32000* NOT 32000D* 
In all cases, NOT has precedence over AND and AND has precedence over OR. 


e Parentheses establish relationships among search terms so that the search engine is able to 
interpret how to respond. A set of elementary or more complex queries can be combined, 
separated by parentheses to clearly identify the query structure and override operators’ 
precedence if needed. 


Example: (Title ~ equal treatment) NOT (Type_ Sector = 9) 
This query is equivalent to Title ~ equal treatment NOT Type Sector = 9 


In some cases, it is necessary to include parentheses in a query to modify the precedence. 
Imagine that a user is looking for a document that contains the words ‘equal treatment’ or 
‘equal rights’. One can structure the query as following: 


Title ~ equal AND (treatment OR rights) 


If he omits the parentheses, the search engine will look for documents that contain either 
the words “equal treatment” or “rights” (or both). 


e A date or a number can be entered as an exact value or a range of values. The following 
operators are valid to enter queries with a range of values: < (smaller than), <= (smaller or 
equal to), > (greater than), >= (greater or equal to), <> (is not equal to). 


Examples: Date_of_document >= 25/12/2000 
DN<72000L0094 
e Some metadata contain codes as well as labels to identify a value. The user can either use 
the search on codes or labels. Using a ‘_CODED’ suffix for a metadata will imply searches on 


codes only. Using a ‘ DECODED’ suffix will only perform the query on the label of a value. If 
no suffix is specified, the system searches on labels and codes. 
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4.1.2 SEARCH ON TITLE OR TEXT 


When no parentheses or quotes are specified, the system will by default search for an exact 
match for the string of words specified. 


Example: Title= genetically modified organism 


This query will search for all documents containing the sequence of words 
“genetically modified organism” in the title. 


If a user needs to look for a title that contains all words regardless of the order, he uses the 
AND operator. 


Example: Title ~ genetically AND modified AND organism 
This query will search for documents that contain all the words in any order. 


Parentheses can be used in this last case to structure the query. However, a user should pay 
attention if he looks for titles that contain parentheses themselves. In this case, he needs to 
put the query into quotes “” to clearly identify that the parentheses are not used as a 
structure. 
Example: Title ~ the European Economic Community ('the Community’) is not a valid 
query, to be sure that the search engine performs the search correctly, use Title ~ 
"the European Economic Community (‘the Community')" 


Proximity operators can be used to search for terms in a specific range of words. They can be 
used in a range of approximately 10 (using the operator “&se”) or 40 (using the operator 
“&pa”) words. 


Example: Text ~ transport &se perishable will search for documents that contain the 
words transport and perishable within the same sentence (10 words) 


Text ~ transport &pa perishable will search for documents that contain the words 
transport and perishable within the same paragraph (40 words) 


Note that even if quotes are used, the system will be able to interpret the operator and use 
the proximity operators correctly. 


It is important to note that proximity operators are only available for full text searches. If, in 
a query, one wishes to combine metadata value search with text searches using proximity 
operators, both terms must clearly be separated with an AND Boolean expression (OR is not 
permitted). 


Example: (Text ~ transport &pa perishable) AND (DD>01/01/2000 OR DN=3*) is a valid query 
(Text ~ “transport &pa perishable” OR DN=3*) AND (DD>01/01/2000) is not a valid query 


(Text ~ transport &pa perishable) OR (DD>01/01/2000 OR DN=3*) is not valid either. 
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4.1.3 SEARCH ON DATES 


e The search on dates can be performed using the operators =, >, <, <=, >= (e.g. 
DD>01/01/2000). 


e It is also possible to search using relative dates using the keywords TODAY, MONTHS and 
DAYS. For instance DD = TODAY — 5 DAYS 


4.1.4 SEARCH ON CELEX NUMBERS 


e The Set function can be used to find documents within a collection of CELEX numbers. The 
different numbers need to be separated by commas. 


Example: SET(72008L0063, 21992A1231(11), 31977R3024) will return 3 documents. 
Note that truncation operators can also be used in this case. 


e The use of parentheses is not allowed in a CELEX number for a search. This means that 
DN=21992A1231(11) will create an error in the expert search, because parentheses are used 
to establish relationships among search terms. If one needs to look for the document with 
CELEX number 21992A1231(11), he need to use quotes. A valid query is: 


DN=”"21992A1231(11)” 


Attention should be paid to all reserved words as for example AND, OR, etc. Those words refer to 
expert search options. 


4.2 SELECT CLAUSE 


It is possible to extend the expert search query to select the metadata that will be retrieved in the 
search result. The keyword SELECT must be used with the list of names of metadata that the user 
want to retrieve, separated by comma. The use of the SELECT clause is used in combination with the 
WHERE clause. The content of the WHERE clause is described in the section Where clause. 


Example: SELECT TI_DISPLAY,DN,DD WHERE TI ~ transport OR TE ~ transport 


This query will retrieve the documents the word “transport” in their title or text. The 
retrieved result will only contain the metadata TI_DISPLAY (title), DN (celex number) and DD 
(document date). 


4.3 ORDER CLAUSE 


It is possible to retrieve results sorted with a particular metadata. The order clause can be used to 
perform such operation. The syntax is: 


QUERY ORDER BY metadata_1 (ASC| DESC), metadata_2 (ASC| DESC)... 
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So, the ORDER BY keyword is used with a list of metadata separated by comma. The order of sorting 
must by specified: 

e ASC: ascending order; 

e DESC: descending order. 
The order clause is used with a query that can be very simple, as described in Where clause or that 
contain select and where clauses, as described in Select clause. 


Examples: 


O Tl™~ transport OR TE ~ transport ORDER BY DN ASC, TI_DISPLAY ASC 


will select all documents containing the word “transport” in their title or text. The 
result will be sorted, firstly by celex number, ascending order and secondly by title, 
ascending order also. 


O SELECT DN,TI,DD WHERE TI ~ transport OR TE ~ transport ORDER BY DN ASC, 
TI_DISPLAY ASC 


The order clause can also be used in combination with the select and where clauses. 
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5 RESTRICTIONS 


This section describes the restrictions implemented following the Autonomy recommendations to 
avoid bad performing queries. 


5.1 SEARCH BEGINNING WITH A WILDCARD (* OR ?) 


The following wildcard operators are no more available at the beginning of a search: 
e *:zero or more characters (i.e. DN = *2008D0438) ; 
e ?: zero or one character (i.e. DN = 22008438). 

5.1.1 EXAMPLE OF RESTRICTION 


This section describes an example of request with old query syntax and the response provided by the 
current system. 


5.1.1.1 Web service request 





<soap:Envelope xmlins:soap="http://www.w3.org/2003/05/soap-envelope" 
xmins:sear="http://eur-lex.europa.eu/search"> 
<soap:Header> 
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oaSsis -200401-wss- 
wssecurity-secext-1.0.xsd" soap:mustUnderstand="true"> 
<wsse:UsernameToken xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis -200401-wss- 
wssecurity-utility-1.0.xsd" wsu:Id="UsernameToken-1"> 
<wsse: Username>genglefr</wsse:Username> 
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis -200401-wss- 
username-token-profile-1.0#PasswordText"> 
uAsIUm9QUIDF 
</wsse:Password> 
</wsse:UsernameToken> 
</wsse:Security> 
</soap:Header> 
<soap:Body> 
<sear : searchRequest> 
<sear:expertQuery><![CDATA[DN = ?2008438]]></sear:expertQuery> 
<sear : page>1</sear : page> 
<sear :pageSize>10</sear : pageSize> 
<sear :exactCount>true</sear :exactCount> 
<sear : searchLanguage>en</sear : searchLanguage> 
</sear : searchRequest> 
</soap:Body> 
</soap:Envelope> 











Table 5: Web service call with wildcard 


5.1.1.2 Web service response 





<S:Envelope xmins:S="http://www.w3.org/2003/05/soap-envelope"> 
<S:Body> 
<ns3:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/" 


xmlns:ns3="http://www.w3.org/2003/05/soap-envelope"> 
<ns3:Code> 
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<ns3:Value> 
ns3:Sender 
</ns3:Value> 
<ns3:Subcode> 
<ns3:Value xmlns:nsi="http://eur-lex.europa.eu/search"> 
ns1:WS_QUERY_SYNTAX_ERROR 
</ns3:Value> 
</ns3:Subcode> 
</ns3:Code> 
<ns3:Reason> 
<ns3:Text xml:lang="en"> 
The operator ? is not compatible with the metadata DN. 
</ns3:Text> 
</ns3:Reason> 
</ns3:Fault> 
</S:Body> 
</S:Envelope> 











Table 6: Response for a wildcard query 


5.1.2 CORRECTION 


In order to correct the old query, the beginning wildcard character has to be removed: 





<soap:Envelope xmins:soap="http://www.w3.org/2003/05/soap-envelope" 
xmins:sear="http://eur-lex.europa.eu/search"> 
<soap:Header> 
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss- 
wssecurity-secext-1.0.xsd" soap:mustUnderstand="true"> 
<wsse:UsernameToken xmins:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss- 
wssecurity-utility-1.0.xsd" wsu:Id="UsernameToken-1"> 
<wsse:Username>genglefr</wsse:Username> 
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis -200401-wss- 
username -token-profile-1.0#PasswordText"> 
UASIUMQUIDF 
</wsse:Password> 
</wsse:UsernameToken> 
</wsse:Security> 
</soap:Header> 
<soap : Body> 
<sear : searchRequest> 
<sear :expertQuery><![CDATATSELECT DN,XC_ DISPLAY WHERE DN = 02008D0438 OR 12008D0438 OR 
22008D0438 OR 32008D0438 OR 42008D0438 OR 52008D0438 OR 62008D0438 OR 72008D0438 OR 
82008D0438 OR 92008D0438] ]></sear:expertQuery> 
<sear : page>1</sear : page> 
<sear :pageSize>10</sear : pageSize> 
<sear :exactCount>true</sear :exactCount> 
<sear : searchLanguage>en</sear : searchLanguage> 
</sear : searchRequest> 
</soap:Body> 
</soap:Envelope> 





Table 7: Corrected web service call without wildcard 


5.2 STRICTLY HIGHER/LOWER TEXTUAL OPERATOR 


The system allowed to perform comparison on textual metadata like >, <, >= and <=. 
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In order to perform a strictly higher or strictly lower operator, the system was using a not match 
criteria to only include higher or lower values in the result list. Following the recommendations, using 
a not match criteria can decrease the search response time. 


Note that numeric metadata are not affected by this recommendation as the system can determine 
the values to include in the search result. 


5.2.1 EXAMPLE OF RESTRICTION 


This section describes an example of request with old query syntax and the response provided by the 
current system. 


5.2.1.1 Web service request 





<soap:Envelope xmins:soap="http://www.w3.org/2003/05/soap-envelope" 
xmins:sear="http://eur-lex.europa.eu/search"> 
<soap:Header> 
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss- 
wssecurity-secext-1.0.xsd" soap:mustUnderstand="true"> 
<wsse:UsernameToken xmlins:wsu="http://docs.oasis-open.org/wss/2004/01/oasis -200401-wss- 
wssecurity-utility-1.0.xsd" wsu:Id="UsernameToken-1"> 
<wsse:Username>genglefr</wsse:Username> 
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis -200401-wss- 
username -token-profile-1.0#PasswordText"> 
UASIUMQUIDF 
</wsse:Password> 
</wsse:UsernameToken> 
</wsse:Security> 
</soap:Header> 
<soap:Body> 
<sear : searchRequest> 
<sear:expertQuery><! [CDATA[SELECT XC_ DISPLAY WHERE DN > 
320080D438] ]></sear :expertQuery> 
<sear : page>1</sear : page> 
<sear :pageSize>10</sear : pageSize> 
<sear :exactCount>true</sear :exactCount> 
<sear : searchLanguage>en</sear : searchLanguage> 
</sear : searchRequest> 
</soap:Body> 
</soap:Envelope> 











Table 8: Web service call with higher/lower textual operator 


5.2.1.2 Web service response 





<S:Envelope xmins:S="http://www.w3.org/2003/05/soap-envelope"> 
<S:Body> 
<ns3:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ns3="http://www.w3.org/2003/05/soap-envelope"> 
<ns3:Code> 
<ns3:Value> 
ns3:Sender 
</ns3:Value> 
<ns3:Subcode> 
<ns3:Value xmlns:nsi="http://eur-lex.europa.eu/search"> 
ns1:WS_QUERY_SYNTAX_ERROR 
</ns3:Value> 
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</ns3:Subcode> 

</ns3:Code> 

<ns3:Reason> 
<ns3:Text xml:lang="en"> 

The operator > is not compatible with the metadata DN. 

</ns3:Text> 

</ns3:Reason> 

</ns3:Fault> 
</S:Body> 
</S:Envelope> 











Table 9: Response from call with higher/lower textual operator 


5.2.2 CORRECTION 


Comparison operators for textual metadata are limited to higher/lower or equal operators. This 
restriction causes the value to be included in the search result. 


Here is an example of corrected query: 





<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
xmlns:sear="http://eur-lex.europa.eu/search"> 
<soap:Header> 
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis -200401-wss- 
wssecurity-secext-1.0.xsd" soap:mustUnderstand="true"> 
<wsse:UsernameToken xmlins:wsu="http://docs.oasis-open.org/wss/2004/01/oasis -200401-wss- 
wssecurity-utility-1.0.xsd" wsu:Id="UsernameToken-1"> 
<wsse :Username>genglefr</wsse:Username> 
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss- 
username-token-profile-1.0#PasswordText"> 
UASIUMQUIDF 
</wsse:Password> 
</wsse:UsernameToken> 
</wsse:Security> 
</soap:Header> 
<soap:Body> 
<sear : searchRequest> 
<sear:expertQuery><! [CDATA[SELECT XC_ DISPLAY WHERE DN >= 
320080D438] ]></sear :expertQuery> 
<sear : page>1</sear : page> 
<sear :pageSize>10</sear : pageSize> 
<sear :exactCount>true</sear :exactCount> 
<sear : searchLanguage>en</sear : searchLanguage> 
</sear : searchRequest> 
</ soap :Body> 
</soap:Envelope> 











Table 10: Correction of web service call with higher/lower textual operator 


5.3 RESTRICTED FULL TEXT METADATA 


Previously, the system allowed configuring large text metadata to perform match operation (i.e. on 
the text of the document). 
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Large text metadata have been restricted to full text search operator (~). The exhaustive list of 
restricted metadata is: 

- TI 

- TE 

- CM 

- MI 

- NOM_USEL 

- MEMBER STATE 

- INSTITUTION 

- IX 

- [1 

- (2 

- MO 

- VS 

- CO 

- DI 

- DESCRIPTORS 

-  LP_INITIATING DATE 


5.3.1 EXAMPLE OF RESTRICTION 


This section describes an example of request with old query syntax and the response provided by the 
current system. 


5.3.1.1 Web service request 





<soap:Envelope xmlins:soap="http://www.w3.org/2003/05/soap-envelope" 
xmlns:sear="http://eur-lex.europa.eu/search"> 
<soap:Header> 
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss- 
wssecurity-secext-1.0.xsd" soap:mustUnderstand="true"> 
<wsse:UsernameToken xmlins:wsu="http://docs.oasis-open.org/wss/2004/01/oasis -200401-wss- 
wssecurity-utility-1.0.xsd" wsu:Id="UsernameToken-1"> 
<wsse:Username>genglefr</wsse:Username> 
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis -200401-wss- 
username -token-profile-1.0#PasswordText"> 
UASIUMQUIDF 
</wsse:Password> 
</wsse:UsernameToken> 
</wsse:Security> 
</soap:Header> 
<soap : Body> 
<sear : searchRequest> 
<sear:expertQuery><! [CDATA[SELECT XC_ DISPLAY WHERE TI = 
transport*]]></sear:expertQuery> 
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<sear :page>1</sear : page> 
<sear :pageSize>10</sear : pageSize> 
<sear :exactCount>true</sear :exactCount> 
<sear : searchLanguage>en</sear : searchLanguage> 
</sear: searchRequest> 
</soap : Body> 
</soap:Envelope> 











Table 11: Web service call with restricted full text metadata 


5.3.1.2 Web service response 





<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope"> 
<S:Body> 
<ns3:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/" 
xmLlns:ns3="http://www.w3.org/2003/05/soap-envelope"> 
<ns3:Code> 
<ns3:Value> 
ns3:Sender 
</ns3:Value> 
<ns3:Subcode> 
<ns3:Value xmlins:ns1="http://eur-lex.europa.eu/search"> 
ns1:WS_QUERY_SYNTAX_ERROR 
</ns3:Value> 
</ns3:Subcode> 
</ns3:Code> 
<ns3:Reason> 
<ns3:Text xml: lang="en"> 
The operator = is not compatible with the metadata TI. 
</ns3:Text> 
</ns3:Reason> 
</ns3:Fault> 
</S:Body> 
</S:Envelope> 





Table 12: Response from call with restricted full text metadata 


5.3.2 CORRECTION 


In order to correct the old query, the equal operator has to be replaced by the tilde (~) operator. 


<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
xmins:sear="http://eur-lex.europa.eu/search"> 
<soap:Header> 
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis -200401-wss- 
wssecurity-secext-1.0.xsd" soap:mustUnderstand="true"> 
<wsse:UsernameToken xmins:wsu="http://docs.oasis-open.org/wss/2004/01/oasis -200401-wss- 
wssecurity-utility-1.0.xsd" wsu:Id="UsernameToken-1"> 
<wsse :Username>genglefr</wsse:Username> 
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis -200401-wss- 
username -token-profile-1.0#PasswordText"> 
UASIUMQUIDF 
</wsse:Password> 
</wsse:UsernameToken> 
</wsse:Security> 
</soap:Header> 
<soap : Body> 
<sear : searchRequest> 
<sear:expertQuery><![CDATA[SELECT XC_DISPLAY WHERE TI ~ transport]]></sear:expertQuery> 
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<sear :page>1</sear : page> 
<sear :pageSize>10</sear : pageSize> 
<sear :exactCount>true</sear :exactCount> 
<sear : searchLanguage>en</sear : searchLanguage> 
</sear : searchRequest> 
</soap:Body> 
</soap:Envelope> 











Table 13: Correction of web service call with restricted full text metadata 


End of Document 
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